<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Handshaking (Servers)</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Boost.Beast">
<link rel="up" href="../using_websocket.html" title="Using WebSocket">
<link rel="prev" href="handshaking_clients.html" title="Handshaking (Clients)">
<link rel="next" href="send_and_receive_messages.html" title="Send and Receive Messages">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="handshaking_clients.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="send_and_receive_messages.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="beast.using_websocket.handshaking_servers"></a><a class="link" href="handshaking_servers.html" title="Handshaking (Servers)">Handshaking
      (Servers)</a>
</h3></div></div></div>
<p>
        A <a class="link" href="../ref/boost__beast__websocket__stream.html" title="websocket::stream"><code class="computeroutput"><span class="identifier">stream</span></code></a> automatically handles receiving
        and processing the HTTP response to the handshake request. The call to handshake
        is successful if a HTTP response is received with the <a href="https://tools.ietf.org/html/rfc6455#section-4.2.2" target="_top"><span class="emphasis"><em>101
        Switching Protocols</em></span></a> status code. On failure, an error
        is returned or an exception is thrown. Depending on the keep alive setting,
        the connection may remain open for a subsequent handshake attempt.
      </p>
<p>
        Performing a handshake for an incoming websocket upgrade request operates
        similarly. If the handshake fails, an error is returned or exception thrown:
      </p>
<pre class="programlisting"><span class="identifier">ws</span><span class="special">.</span><span class="identifier">accept</span><span class="special">();</span>
</pre>
<p>
        Successful WebSocket Upgrade responses generated by the implementation will
        typically look like this:
      </p>
<div class="table">
<a name="beast.using_websocket.handshaking_servers.decorated_websocket_upgrade_http"></a><p class="title"><b>Table&#160;1.26.&#160;Decorated WebSocket Upgrade HTTP Request</b></p>
<div class="table-contents"><table class="table" summary="Decorated WebSocket Upgrade HTTP Request">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Serialized Octets
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody><tr>
<td>
<pre class="programlisting"><span class="identifier">HTTP</span><span class="special">/</span><span class="number">1.1</span> <span class="number">101</span> <span class="identifier">Switching</span> <span class="identifier">Protocols</span>
<span class="identifier">Upgrade</span><span class="special">:</span> <span class="identifier">websocket</span>
<span class="identifier">Connection</span><span class="special">:</span> <span class="identifier">upgrade</span>
<span class="identifier">Sec</span><span class="special">-</span><span class="identifier">WebSocket</span><span class="special">-</span><span class="identifier">Accept</span><span class="special">:</span> <span class="identifier">s3pPLMBiTxaQ9kYGzzhZRbK</span><span class="special">+</span><span class="identifier">xOo</span><span class="special">=</span>
<span class="identifier">Server</span><span class="special">:</span> <span class="identifier">Beast</span><span class="special">/</span><span class="number">40</span>
</pre>
              </td>
<td>
                <p>
                  The <a href="https://tools.ietf.org/html/rfc6455#section-11.3.3" target="_top"><span class="emphasis"><em>Sec-WebSocket-Accept</em></span></a>
                  field value is generated from the request in a fashion specified
                  by the WebSocket protocol.
                </p>
              </td>
</tr></tbody>
</table></div>
</div>
<br class="table-break"><h5>
<a name="beast.using_websocket.handshaking_servers.h0"></a>
        <span class="phrase"><a name="beast.using_websocket.handshaking_servers.decorators"></a></span><a class="link" href="handshaking_servers.html#beast.using_websocket.handshaking_servers.decorators">Decorators</a>
      </h5>
<p>
        If the caller wishes to add or modify fields, the member functions <a class="link" href="../ref/boost__beast__websocket__stream/accept_ex.html" title="websocket::stream::accept_ex"><code class="computeroutput"><span class="identifier">accept_ex</span></code></a> and <a class="link" href="../ref/boost__beast__websocket__stream/async_accept_ex.html" title="websocket::stream::async_accept_ex"><code class="computeroutput"><span class="identifier">async_accept_ex</span></code></a> are provided which
        allow an additional function object, called a <span class="emphasis"><em>decorator</em></span>,
        to be passed. The decorator is invoked to modify the HTTP Upgrade request
        as needed. This example sets the Server field on the response:
      </p>
<pre class="programlisting"><span class="identifier">ws</span><span class="special">.</span><span class="identifier">accept_ex</span><span class="special">(</span>
    <span class="special">[](</span><span class="identifier">response_type</span><span class="special">&amp;</span> <span class="identifier">m</span><span class="special">)</span>
    <span class="special">{</span>
        <span class="identifier">m</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="identifier">http</span><span class="special">::</span><span class="identifier">field</span><span class="special">::</span><span class="identifier">server</span><span class="special">,</span> <span class="string">"MyServer"</span><span class="special">);</span>
    <span class="special">});</span>
</pre>
<p>
        The HTTP Upgrade response produced by the previous call looks like this:
      </p>
<div class="table">
<a name="beast.using_websocket.handshaking_servers.decorated_websocket_upgrade_htt0"></a><p class="title"><b>Table&#160;1.27.&#160;Decorated WebSocket Upgrade HTTP Request</b></p>
<div class="table-contents"><table class="table" summary="Decorated WebSocket Upgrade HTTP Request">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                <p>
                  Serialized Octets
                </p>
              </th>
<th>
                <p>
                  Description
                </p>
              </th>
</tr></thead>
<tbody><tr>
<td>
<pre class="programlisting"><span class="identifier">HTTP</span><span class="special">/</span><span class="number">1.1</span> <span class="number">101</span> <span class="identifier">Switching</span> <span class="identifier">Protocols</span>
<span class="identifier">Upgrade</span><span class="special">:</span> <span class="identifier">websocket</span>
<span class="identifier">Connection</span><span class="special">:</span> <span class="identifier">upgrade</span>
<span class="identifier">Sec</span><span class="special">-</span><span class="identifier">WebSocket</span><span class="special">-</span><span class="identifier">Accept</span><span class="special">:</span> <span class="identifier">s3pPLMBiTxaQ9kYGzzhZRbK</span><span class="special">+</span><span class="identifier">xOo</span><span class="special">=</span>
<span class="identifier">Server</span><span class="special">:</span> <span class="identifier">AcmeServer</span>
</pre>
              </td>
<td>
                <p>
                  When the Upgrade request fails, the implementation will still invoke
                  the decorator to modify the response. In this case, the response
                  object will have a status code other than 101.
                </p>
                <p>
                  Undefined behavior results when the upgrade request is successful
                  and the decorator modifies the fields specific to perform the WebSocket
                  Upgrade, such as the Upgrade and Connection fields.
                </p>
              </td>
</tr></tbody>
</table></div>
</div>
<br class="table-break"><h5>
<a name="beast.using_websocket.handshaking_servers.h1"></a>
        <span class="phrase"><a name="beast.using_websocket.handshaking_servers.passing_http_requests"></a></span><a class="link" href="handshaking_servers.html#beast.using_websocket.handshaking_servers.passing_http_requests">Passing
        HTTP Requests</a>
      </h5>
<p>
        When implementing an HTTP server that also supports WebSocket, the server
        usually reads the HTTP request from the client. To detect when the incoming
        HTTP request is a WebSocket Upgrade request, the function <a class="link" href="../ref/boost__beast__websocket__is_upgrade.html" title="websocket::is_upgrade"><code class="computeroutput"><span class="identifier">is_upgrade</span></code></a> may be used.
      </p>
<p>
        Once the caller determines that the HTTP request is a WebSocket Upgrade,
        additional overloads of <a class="link" href="../ref/boost__beast__websocket__stream/accept.html" title="websocket::stream::accept"><code class="computeroutput"><span class="identifier">accept</span></code></a>, <a class="link" href="../ref/boost__beast__websocket__stream/accept_ex.html" title="websocket::stream::accept_ex"><code class="computeroutput"><span class="identifier">accept_ex</span></code></a>, <a class="link" href="../ref/boost__beast__websocket__stream/async_accept.html" title="websocket::stream::async_accept"><code class="computeroutput"><span class="identifier">async_accept</span></code></a>, and <a class="link" href="../ref/boost__beast__websocket__stream/async_accept_ex.html" title="websocket::stream::async_accept_ex"><code class="computeroutput"><span class="identifier">async_accept_ex</span></code></a> are provided which
        receive the entire HTTP request header as an object to perform the handshake.
        In this example, the request is first read in using the HTTP algorithms,
        and then passed to a newly constructed stream:
      </p>
<pre class="programlisting"><span class="comment">// Buffer required for reading HTTP messages</span>
<span class="identifier">flat_buffer</span> <span class="identifier">buffer</span><span class="special">;</span>

<span class="comment">// Read the HTTP request ourselves</span>
<span class="identifier">http</span><span class="special">::</span><span class="identifier">request</span><span class="special">&lt;</span><span class="identifier">http</span><span class="special">::</span><span class="identifier">string_body</span><span class="special">&gt;</span> <span class="identifier">req</span><span class="special">;</span>
<span class="identifier">http</span><span class="special">::</span><span class="identifier">read</span><span class="special">(</span><span class="identifier">sock</span><span class="special">,</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">req</span><span class="special">);</span>

<span class="comment">// See if its a WebSocket upgrade request</span>
<span class="keyword">if</span><span class="special">(</span><span class="identifier">websocket</span><span class="special">::</span><span class="identifier">is_upgrade</span><span class="special">(</span><span class="identifier">req</span><span class="special">))</span>
<span class="special">{</span>
    <span class="comment">// Construct the stream, transferring ownership of the socket</span>
    <span class="identifier">stream</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span><span class="special">&gt;</span> <span class="identifier">ws</span><span class="special">{</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">sock</span><span class="special">)};</span>

    <span class="comment">// Clients SHOULD NOT begin sending WebSocket</span>
    <span class="comment">// frames until the server has provided a response.</span>
    <span class="identifier">BOOST_ASSERT</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>

    <span class="comment">// Accept the upgrade request</span>
    <span class="identifier">ws</span><span class="special">.</span><span class="identifier">accept</span><span class="special">(</span><span class="identifier">req</span><span class="special">);</span>
<span class="special">}</span>
<span class="keyword">else</span>
<span class="special">{</span>
    <span class="comment">// Its not a WebSocket upgrade, so</span>
    <span class="comment">// handle it like a normal HTTP request.</span>
<span class="special">}</span>
</pre>
<h5>
<a name="beast.using_websocket.handshaking_servers.h2"></a>
        <span class="phrase"><a name="beast.using_websocket.handshaking_servers.buffered_handshakes"></a></span><a class="link" href="handshaking_servers.html#beast.using_websocket.handshaking_servers.buffered_handshakes">Buffered
        Handshakes</a>
      </h5>
<p>
        Sometimes a server implementation wishes to read octets on the stream in
        order to route the incoming request. For example, a server may read the first
        6 octets after accepting an incoming connection to determine if a TLS protocol
        is being negotiated, and choose a suitable implementation at run-time. In
        the case where the server wishes to accept the incoming request as an HTTP
        WebSocket Upgrade request, additional overloads of <a class="link" href="../ref/boost__beast__websocket__stream/accept.html" title="websocket::stream::accept"><code class="computeroutput"><span class="identifier">accept</span></code></a>, <a class="link" href="../ref/boost__beast__websocket__stream/accept_ex.html" title="websocket::stream::accept_ex"><code class="computeroutput"><span class="identifier">accept_ex</span></code></a>, <a class="link" href="../ref/boost__beast__websocket__stream/async_accept.html" title="websocket::stream::async_accept"><code class="computeroutput"><span class="identifier">async_accept</span></code></a>, and <a class="link" href="../ref/boost__beast__websocket__stream/async_accept_ex.html" title="websocket::stream::async_accept_ex"><code class="computeroutput"><span class="identifier">async_accept_ex</span></code></a> are provided which
        receive the additional buffered octets and consume them as part of the handshake.
      </p>
<p>
        In this example, the server reads the initial HTTP message into the specified
        dynamic buffer as an octet sequence in the buffer's output area, and later
        uses those octets to attempt an HTTP WebSocket Upgrade:
      </p>
<pre class="programlisting"><span class="comment">// Read into our buffer until we reach the end of the HTTP request.</span>
<span class="comment">// No parsing takes place here, we are just accumulating data.</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">streambuf</span> <span class="identifier">buffer</span><span class="special">;</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">read_until</span><span class="special">(</span><span class="identifier">sock</span><span class="special">,</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="string">"\r\n\r\n"</span><span class="special">);</span>

<span class="comment">// Now accept the connection, using the buffered data.</span>
<span class="identifier">ws</span><span class="special">.</span><span class="identifier">accept</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">.</span><span class="identifier">data</span><span class="special">());</span>
</pre>
<p>
        The implementation uses a fixed-size storage area to hold buffers passed
        using these functions. If an application is reaching the limit of the internal
        buffer size, then the websocket stream may be instantiated with the next
        layer type of <a class="link" href="../ref/boost__beast__buffered_read_stream.html" title="buffered_read_stream"><code class="computeroutput"><span class="identifier">buffered_read_stream</span></code></a> to wrap the
        underlying stream. The buffered handshake data may be first placed into the
        buffered read stream, which uses a dynamically sized buffer.
      </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2016, 2017 Vinnie Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="handshaking_clients.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_websocket.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="send_and_receive_messages.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
